Skip to content

every event says breaking, deprecated or added; every kind emits additions - #257

Merged
adssib merged 7 commits into
mainfrom
c5.10-additions
Nov 21, 2026
Merged

adssib merged 7 commits into
mainfrom
c5.10-additions

Conversation

@adssib

@adssib adssib commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

What this changes

Every event says what it does to code written against the version before it: change = breaking | deprecated | added, as the change-event contract now has it (C5.10 in patch-it, the contract's owner). Additions are data too: every kind emits the ones it can see, with the same care as a removal.

One commit per step, goldens regenerated in the commit that changes them:

Commit Kind Goldens
every event says breaking, deprecated or added all change replaces change_type and breaking (breaking → breaking, deprecation → deprecated, new_feature → added; nothing emitted fix). The fingerprint hashes change where it hashed change_type, so every deprecation's fingerprint is new. Every golden regenerated; nothing else moves (958 events compared with main). contract/fixtures/ synced.
openapi: what a re-released version adds inside itself is filed under it openapi New golden/stripe-api-additions.json (below). No existing golden moves.
apisurface: new modules, classes, functions, methods and optional parameters are added events apisurface 12 goldens gain their pairs' additions: 82 added events. No breaking event moves.
changelog: "Added" and "Features" bullets that name what they add are added events changelog 7 goldens gain their releases' additions: 27 added events. No breaking or deprecated event moves.
catalog: a command new in a release is an added event catalog redis-commands.json gains the 19 commands 8.8-rc1 adds.

Every regenerated golden was checked with a script: each event on main is still there with the same fields, its change the old change_type renamed; what's new is only added events.

Per kind

  • openapi: new operations, parameters, schema properties, enum values and oneOf members were already found by the differ; they're now added events. Providers whose spec history showed "new" operations were mostly moved or re-added ones (vercel, sentry, appwrite, and the other DeprecationsOnly filters) keep dropping them, and their filters now say why (precision over recall). GitLab and Flagsmith (request side only) file request-side additions.
  • Stripe, additions inside an API version (adapter.Rereleased): the change into a version is read from the first release whose latest/openapi.spec3.json declares it, so nothing Stripe adds inside a version is filed with the changes between two versions; what the version's later releases add is filed under the version itself (previous_version = version), additions only. A pair of two releases of one version is additions only. Measured on real releases: 2026-08-26.dahlia (v2516) → 2026-09-30.endive gives the 64 breaking and 837 added changes between the versions, read from v2525, plus the two enum values Stripe added inside 2026-09-30.endive by v2526. The golden replays this on real spec excerpts (v2516, v2524, v2525, v2592: two schemas, values unchanged).
  • apisurface: what's new is read the same way as what's gone, the other way round: a name the older release bound, couldn't read, or a method moved up to a base class isn't new; a new class's members are part of its addition; a TypeScript parameter is new only at the end with every older one in place. A new parameter with a default is added_parameter; a new required one stays a logged note (no subject for it).
  • changelog: under an "Added" or "Features" heading, a bullet that plainly names what it adds ("Added Client.stream method", "Add a to B", "Added timeout parameter to Client.send"). A feature told in words, names with no owner, a list mixing owned and bare names, a constant "to" a type, or "support for X" with nothing it's on is no event. A JSON changelog's endpoint-added is an addition, unless the endpoint is coming back after a removal.
  • catalog: a Redis command new in a release; a name that leaves one file and arrives in another is a file moved. GitHub's upcoming changes list removals only.
  • migrationguide, notices: nothing to add: they list removals and shutdowns.

Drop tests

A drop test now means "nothing that breaks or deprecates": additions are expected there (the apisurface helper, the redis drop pair's 17 additions, the scaffolded drop fixtures, MongoDB's newest day with its one new endpoint).

Checklist

  • Metadata complete in the registration: stripe/api's and redis/commands' "watches" now say they report additions; I read the words. The other sources' metadata didn't change.
  • Every commit is signed off (git commit -s, DCO)
  • Golden test over a real saved copy of the source: stripe/testdata/openapi/ (spec excerpts), redis/testdata/redis-8.8-rc1-*.json and redis-8.10.0-*.json (whole command files)
  • testdata/README.md lists each new file (Stripe, Redis)
  • One pinned drop test per source: kept, now "nothing breaks" where the pair adds
  • The source's section of providers/<provider>/README.md updated (Stripe, Redis, MongoDB, every apisurface and changelog section)
  • Provider-specific code only in providers/<provider>/; the kinds import no provider
  • Fetches only through env.Get / core/kit/ (Stripe's adapter keeps its own fetch.Get, as before)
  • make check passes locally, and make check PATCH_IT=<patch-it checkout of the contract change> (contract fixtures match)
  • Nothing private

Notes for the reviewer

  • Merge after the contract change in patch-it (its C5.10). contract/fixtures/ here is synced from that change, not from patch-it's main yet; CI_contract skips while patch-it isn't public.
  • The hosted ingestion service needs this release to store change (and to compare a re-released Stripe version's newer releases as a pair of one version). Until it bumps, it keeps the release it pins.
  • Review follow-ups: "support for" (inline note) is now no event unless it names what it's on; notGone returns the base class instead of the move-up check parsing its message. Not done: caching Stripe's releases listing per run (Releases lists them again for each pair, as Versions does per run).
  • plugin.Rereleasing (core): a source says it re-releases versions, so the hosted ingestion service compares a version with itself at a newer release.
  • Calls I made: additions are not filtered back in for the specs measured as noisy (above); a constant "to" a type and a list mixing owned and bare names are dropped rather than guessed; apisurface counts a public name in a TypeScript bundle whose name starts with _ as public, as removals always did.

🤖 Generated with Claude Code

adssib and others added 5 commits November 21, 2026 15:39
change replaces change_type and breaking: breaking stays breaking,
deprecation is deprecated, new_feature is added; nothing emitted fix.
The fingerprint hashes change where it hashed change_type, so every
deprecation's fingerprint is new. Goldens regenerated: each event gets
change in place of change_type and breaking, nothing else moves (958
events checked against main). contract/fixtures synced from patch-it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: adssib <75389300+adssib@users.noreply.github.com>
An adapter whose versions are published again after being named
(adapter.Rereleased, Stripe) has the change into a version read from the
version's first release, and what its later releases add filed under the
version itself (previous_version = version), additions only. A pair of
two releases of one version is additions only. New golden:
stripe-api-additions.json, from real v2516/v2525/v2592 spec excerpts (the
two enum values Stripe added inside 2026-09-30.endive). No existing golden
moves.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: adssib <75389300+adssib@users.noreply.github.com>
…ameters are added events

The surfaces compared for removals are compared the other way too, with
the same care: a name the older release bound, couldn't read, or a
method moved up to a base class isn't new; a new class's members are its
addition; a TypeScript parameter is new only at the end with every older
one in place. Goldens regenerated: 12 apisurface goldens gain their
pairs' additions (82 added events); no breaking event moves. A drop pair
may add: it must store nothing that breaks or deprecates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: adssib <75389300+adssib@users.noreply.github.com>
… added events

A bullet under an Added or Features heading is read with the same care as
a removal: names added plainly ("Added `X` method", "Add `a` to `B`"),
or a parameter given a call ("Added `p` parameter to `f`"). A feature
told in words, names with no owner, a list mixing owned and bare names,
or a constant "to" a type is no event. A JSON changelog's endpoint-added
is an added event, unless the endpoint is coming back after a removal.
Goldens regenerated: 7 changelog goldens gain their releases' additions
(27 added events); no breaking or deprecated event moves.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: adssib <75389300+adssib@users.noreply.github.com>
A command file in the newer release's listing and not the older's is
fetched at the newer tag and filed as added_symbol, quoting it; a command
whose name leaves one file and arrives in another is a file moved:
neither. redis-commands.json gains the 19 commands 8.8-rc1 adds (the
array commands and INCREX), from their real files; the drop pair's 17
additions are added events and nothing breaks. GitHub's upcoming changes
list removals only: no additions to read there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: adssib <75389300+adssib@users.noreply.github.com>
@claude

claude Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

Claude finished @adssib's task in 1m 45s —— View job


✅ Ready to merge once the patch-it contract change (C5.10) is in: the code builds, every test passes, the metadata and pages are updated, and every golden change is explained in the PR. I found no blocking bugs.

Rules

Rule Status Evidence
Metadata in the registration (Rule 1) ✅ Only two sources' wording changed: stripe/api (providers/stripe/provider.go:20) and redis/commands (providers/redis/provider.go:21). Both "watches" now say they report additions, and I read the wording. No list kept by hand was added back.
Provider pages ✅ The pages for Stripe, Redis, MongoDB and every apisurface and changelog provider say they report additions. go test ./providers/all passes.
Golden test + quote ✅ New stripe-api-additions.json from real spec excerpts (v2516/v2524/v2525/v2592), and new Redis 8.8-rc1 / 8.10.0 command files, each with a row in its testdata/README.md. The PR explains every regenerated golden: renamed fields, plus added events only.
Drop test ✅ Each source keeps its drop test. It now means "nothing breaks or deprecates", so a pair that only adds things is still a drop. The PR says this and the reason holds.
Kind/provider split ✅ adapter.Rereleased is a general interface in kinds/openapi/adapter, and only Stripe implements it. No kind imports a provider.
Fetch only via env ✅ Catalog fetches the new files through env.Get. Stripe's adapter still uses its own fetch.Get, as it did before this PR.
Contract fixtures ⚠️ merge order contract/fixtures/ was synced from the upstream C5.10 change, which is not on patch-it main yet. Merge that change first, as the PR notes say.
Nothing private (Rule 2) ✅ Leak guard is clean. The commits and the PR body have no internal names, links or people.
DCO ✅ All 5 commits are Signed-off-by and keep the co-author trailer.

Bugs

None found. Things I traced and found correct:

  • openapi.Extract with Rereleased: changes between versions are read from from to the version's first release. What later releases add is read from the first release to to, additions only. The errNotThereYet skip and the fallback "no earlier release declares it, so use to" both behave correctly.
  • apisurface additions: a symbol is not reported as new when its older release still binds it (notGone with the releases swapped), when its parent class or module is itself new, when it is a rename target, or when it moved up to a base class. A new required parameter is still only logged.
  • Redis: a command whose file moved is excluded from both removals and additions.
  • MongoDB: an endpoint-added for an endpoint coming back after a removal is suppressed.

Verified

  • go build ./...: ok
  • go vet ./...: ok
  • gofmt -l .: prints nothing
  • go test -race ./...: passes (exit 0)
  • python3 scripts/leak_guard.py --all: "no banned terms (8 hashed terms checked)"
  • I did not run make check PATCH_IT=… because there is no patch-it checkout here.

Non-blocking

  • Changelog "support for" (inline): I worked this out from the regexes but couldn't run it to confirm. Added support for `pyproject.toml` (or `brotli`) should match addedActive with no noun and become an added_symbol event. "Support for X" usually names something outside the package, not a symbol it exports. Consider requiring a noun after support for, and add a pinned drop case.
  • Stripe Releases cost: every pair Extract calls apiVersions, which pages through all stripe/openapi releases again. A backfill over many versions repeats that listing once per pair, unless the fetch cache answers the pages with 304s. Caching the listing for each Extract run would avoid this.
  • apisurface movedUp: it gets the base class name back by parsing the text of notGone's message ("its base class %s defines it", apisurface.go:321). If that wording changes, the check silently stops working. Returning the base name as a value would make it sturdier.

The hosted ingestion service compares the newest version again, as a pair
of one version, when its release moves; openapi says yes for an adapter
that re-releases (Stripe).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: adssib <75389300+adssib@users.noreply.github.com>
// ("Added `Client.stream` method", "Add `a` and `b` to `Widget`", "New
// `foo` function", "`bar` was added"), or a parameter it gives a call
// ("Added `timeout` parameter to `Client.send`").
addedActive = regexp.MustCompile(`(?i)^(?:added|adds|add|introduced|introduces|introduce|new)(?: support for)? (?:the |a |an )?(?:new )?(?:` + noun + ` )?` + list + `(?: ` + noun + `)?(?: (?:to|on|in) (?:the )?(?:` + noun + ` )?(§)(?: ` + noun + `)?)?$`)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Precision (non-blocking, worth a look): (?: support for)? lets a bullet like Added support for `pyproject.toml` or Add support for `brotli` match with a bare § and no noun. cleanName accepts both (pyproject.toml passes ident as a dotted name), so the event says "pyproject.toml was added in ". "Support for X" usually names something outside the package (a file format, an encoding, a library), not a symbol it now exports.

I didn't see this in the current goldens. Two possible fixes: require a noun when support for is present, or drop support for from the added templates and add a pinned drop case to parse_test.go.

…Gone returns the base class

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: adssib <75389300+adssib@users.noreply.github.com>
@adssib
adssib merged commit 679b3c5 into main Nov 21, 2026
4 checks passed
@adssib
adssib deleted the c5.10-additions branch November 21, 2026 21:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant